home *** CD-ROM | disk | FTP | other *** search
/ 3D Images / 3D Images.iso / programs / amiga / rayshade / inetray / readme < prev    next >
Text File  |  1995-01-12  |  11KB  |  253 lines
  1. ======================================================================
  2.                     R E A D M E 
  3.                     doc: Fri Mar  6 16:04:58 1992
  4.                     dlm: Wed Jul 21 14:38:30 1993
  5.                     (c) 1992 ant@ips.id.ethz.ch
  6.                     uE-Info: 37 16 NIL 0 0 72 3 2 8 ofnI
  7. ======================================================================
  8.  
  9. NOTE: Read the file RELNOTES for a short description of the changes
  10.       since the last version.
  11.  
  12. NOTE: The email address listed in most file headers is an obsolete one.
  13.       The correct address is ant@bernina.ethz.ch
  14.  
  15. Whatis Inetray
  16. --------------
  17. Inetray is an application allowing you to concurrently raytrace an
  18. image using a lot of machines. The task is dynamically distributed to
  19. all machines offering this service.
  20.  
  21. Requirements
  22. ------------
  23. You need the following software libraries to run Inetray:
  24.     - BSD-style sockets
  25.     - SUN rpc-library (at least version 4.0)
  26.     - SUN xdr-library (at least version 4.0)
  27.     - rayshade 4.0.6 (or later, but must be compatible)
  28. The only thing you probably need to check is if you have the SUN
  29. rpc-library since this uses the other two communications libraries.
  30. On all machines where you want to run servers, you need to have a local
  31. portmapper running.
  32.  
  33. Documentation
  34. -------------
  35.     README        This file
  36.     POO        Principles of operation; some internals
  37.     INSTALL        compilation & installation manual
  38.     SUPPORT        supported machines and quirks
  39.     FAQ        Frequently asked questions
  40.     HISTORY        A short program history (patches, releases, ...)
  41.     TODO        Things to do (Todo que nunca voy a hacer...)
  42.     RELNOTES    Release notes
  43.  
  44. Examples
  45. --------
  46. Any rayshade examples work, but I included an image which uses lots of
  47. CPU time to calculate. It's called mole.ray.
  48.  
  49. Copyright
  50. ---------
  51. Feel free to copy the software for non-commercial purposes. Note,
  52. however, that this software is not GNU; this means that it was never
  53. intended to be a monster and I will not allow it to become one.
  54.  
  55. Author
  56. ------
  57. Andreas Thurnherr (ant@bernina.ethz.ch), currently probably travelling
  58. somewhere.
  59.  
  60. Support
  61. -------
  62. I will try to give limited support to people trying to port Inetray to
  63. new machines; you can mail me to the address given above. Please read
  64. the docs before mailing me.
  65.  
  66. Credits
  67. -------
  68. I'd like to thank the people of IPS for allowing me to use their
  69. machines for the development of Inetray - parts of it was also
  70. developed during work hours.
  71. Furthermore, I'd like to thank the team of active beta-testers (David
  72. DeBry, Marvin Landis, Michael Graff, Benny Yih and Rick Braumoeller - I
  73. sure hope I didn't forget anybody) for sticking with me thru all the
  74. 0.X.X versions, bugs and features.
  75. Special thanks to Nikolaos Fotis from Greece who wanted everything,
  76. refused to read the docu and really influenced the user friendliness a
  77. lot.
  78. For version 2 I thank the people of CSCS for letting me basically do
  79. whatever I wanted.
  80.  
  81. Components
  82. ----------
  83. Inetray consists of the following executables:
  84.     inetray        the frontend dispatcher; the client
  85.     rpc.inetrayd    the worker; the server
  86.     inetray.ping    pinger to check response of servers
  87.     inetray.kill    killer; kills all running servers
  88.     inetray.start    startup daemon for rpc.inetrayd
  89.     rpc.dereg    deregister utility for SUNRPC
  90.     netinfo        prints all network addresses of local host
  91.     irstart        starts inetray.start servers on remote hosts
  92.     generr        simulate an error message of a worker
  93.  
  94. Terminology
  95. -----------
  96. The terms worker and server both refer to rpc.inetrayd. The server is
  97. the parent, servicing RPC requests; the worker is the child doing the
  98. actual work.
  99. The terms dispatcher and client both refer to inetray.
  100.  
  101. Runtime Errors
  102. --------------
  103. NOTE: Error messages are collected and handled on a per-worker base.
  104.       After a non-successful run you should check the messages files on
  105.       all workers behaving strangely!!!
  106. Inetray error messages fall into two classes: those generated by inetray
  107. and those generated by the rayshade libraries. Inetray tries to write both
  108. classes to the same place: either the syslog messages file or a messages
  109. file in the temp area of your installation (you can run generr to find
  110. out).
  111. This is only possible if your machine correctly supports asyncronous I/O
  112. using a socketpair. If this cannot be done then the errors generated by
  113. the rayshade libraries are written to a file in the temp area - if this
  114. is the case then Inetray writes a note to the messages file telling you
  115. where the rayshade errors have been written to.
  116. Inetray, upon startup, tries to figure out if your machine handles
  117. asyncronous I/O correctly and writes a warning to your messages file if
  118. that doesn't work. In that case you should recompile inetray with the
  119. NOASYNCIO_QUIRK (see SUPPORT for details).
  120.  
  121. Input
  122. -----
  123. Rayshade takes its input either from stdin or from files. The stdin is
  124. distributed to all servers before rendering starts. Input can come from
  125. a number of files; if this is the case then the files (or a copy
  126. thereof) must be accessible from all the worker machines.
  127. The most convenient place to put all input files is in any directory
  128. under the home directory of the user which exists on all machines (e.g.
  129. if the directory $(HOME)/inetray exists on all machines then the .ray
  130. files can be put there (may involve copying). Note that any part of the
  131. path may be a link; when using NFS copying should not be required. The
  132. exact rules for finding the files are described in POO.
  133. Note that even if input is coming from stdin (pipe or stdin redirection)
  134. there are two possibilities that files must be accessed: a) when the
  135. #include CPP diretive is used and b) when rendering heightfields. Those
  136. files must be accessible on all worker machines as well.
  137.  
  138. Random Numbers
  139. --------------
  140. On different architectures, the random generator used by rayshade 4.0
  141. may generate different sequences. This problem has to be fixed in
  142. rayshade since I won't change any code in those libs. I think it will be
  143. fixed in the next release.
  144.  
  145. inetray [params]
  146. ----------------
  147. is supposed to be compatible with ``rayshade''. 
  148. When you start it up, it replies by giving a Session Key (see POO for
  149. details), followed by the list of servers which replied. The list is
  150. composed of the following fields:
  151.  
  152. inet number    : Internet address of remote machine
  153. remote version    : Version of remote rpc.inetrayd
  154. hostname    : Name of remote host (or, rather, primary interface)
  155. remote pid    : Pid of remote server (workers are forked from this)
  156. username    : Effective user id on remote machine
  157. remote directory: Working directory on remote machine
  158.     
  159. After that the total number of workers is given followed by scheduling
  160. information.
  161. After the trace has been completed a sorted statistics is printed. You
  162. can get to this statistic any time during the trace by hitting ^C (i.e.
  163. interrupting it with SIGINT). Interrupting it again while nothing has
  164. changed, gives you the option to abort the program orderly.
  165. Note that hitting ^C when inetray is part of a pipeline or has been
  166. started from within another program (like make) changes this behaviour.
  167. Then, it is shut down immediately.
  168. If inetray terminates without an orderly shutdown, you'll probably have
  169. to issue an inetray.kill to kill all workers and servers. If you don't
  170. do that, the servers will shut themselves down after approximately 1
  171. minute.
  172.  
  173. rpc.inetrayd
  174. ------------
  175. is the server-daemon. It is started either by inetd or by inetray.start.
  176. On receiving a request, it forks a worker and continues waiting. There
  177. can, however only be one request outstanding any one time.
  178. Roughly once every minute the server checks if the dispatcher is still
  179. running. If that's not the case, it kills its worker (if it exists) and
  180. exits with an error message in the syslog.
  181. At the same time it checks if its worker has exited with an exit code
  182. not equal zero; if one is detected (i.e. rayshade library exit or dead
  183. due to a signal) it shuts itself down orderly too.
  184. NOTE: you never start this program from the command-line (see
  185.       INSTALLATION to find out how you DO start it)
  186.  
  187. inetray.ping [Use List]
  188. -----------------------
  189. is a pinger utility. It checks if servers are ready to run for you. To
  190. find out, if a specific server is ready to run, you just write
  191.     ``inetray.ping hostname'',
  192. if you want to check which workers are ready to run, you run
  193. inetray.ping without any arguments.
  194. The argument list can be arbitrarily complicated. Example:
  195.     ``inetray.ping foo UID=12, bar, 124.130.34.0 N=2 UID=13, \
  196.       local N=0, multi N=16''
  197. See Appendix B in INSTALL for details about the Use List.
  198.  
  199. inetray.kill [key]
  200. ------------------
  201. kills all running servers even if they're currently computing. Since
  202. killing works only with the correct session key, inetray.kill needs to
  203. have this key. Usually it takes it from .inetray.key in the current
  204. directory. This file is written by inetray.
  205. You can, however, supply your own key (to override .inetray.key) by
  206. supplying it on the command line.
  207. This utility can be used for a clean shutdown. It can be used while
  208. inetray is still runnning; inetray notes that all the servers have died
  209. and exits in the end.
  210.  
  211. inetray.start [path of rpc.inetrayd]
  212. ------------------------------------
  213. starts rpc.inetrayd (one or more) on request. Another method is to have
  214. them started by inetd. See INSTALLATION for details.
  215. Note that there can only one inetray.start be running on any one host at
  216. any one time.
  217.  
  218. rpc.dereg [prognum versnum]
  219. ---------------------------
  220. deregisters the indicated program/version with the local portmapper.
  221. Note that the same functionality is offered by rpcinfo(8) but it
  222. requires root privileges (another great show of SUN security)
  223.  
  224. netinfo
  225. -------
  226. prints a list of all network interfaces, local addresses and broadcast
  227. addresses installed on the local host. If the host is set up correctly,
  228. it should react to all addresses given.
  229. Actually only the inet interfaces which listen to broadcasts are
  230. printed! 
  231. Note that if netinfo shows more than one interface, the machine is a
  232. gateway; you should not run inetray (the dispatcher) on a gateway since
  233. it produces lots of traffic on both networks!
  234.  
  235. irstart [pattern]
  236. -----------------
  237. searches the current .inetrayrc for lines containing the pattern. Of
  238. these lines it selects the ones starting with ``#@''. These two leading
  239. characters are removed and the remainder of the line passed as a command
  240. to /bin/sh.
  241. The practical abshot of all this is that you can use irstart and your
  242. .inetrayrc file to start remote inetray.start servers. Hosts which
  243. already have an inetray.start running are handled correctly.
  244.  
  245. generr
  246. ------
  247. simulates a rayshade error message. You should run this program to
  248. determine if you compiled inetray with the correct quirks. After you've
  249. run this program, you should try to find the errors on the machine
  250. (generr tells you where).
  251. Note that you should run generr on all workers to be shure no error
  252. message gets lost.
  253.